PC Users 1998 November

home *** CD-ROM | disk | FTP | other *** search

/ PC Users 1998 November / Cd users extra 14.iso / prog / inst / mailc / see4c_u.txt < prev next >

Wrap

Text File | 1998-09-14 | 45.6 KB | 1,322 lines

SMTP/POP3 Email Engine Library for C/C++ (SEE4C) USERS MANUAL Version 2.0 September 14, 1998 This software is provided as-is. There are no warranties, expressed or implied. Copyright (C) 1998 All rights reserved MarshallSoft Computing, Inc. Post Office Box 4543 Huntsville AL 35815 Voice : 256-881-4630 FAX : 256-880-0925 email : info@marshallsoft.com web : www.marshallsoft.com _______ ____|__ | (R) --+ | +------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals --+--+ | +--------------------- |___|___| MEMBER MARSHALLSOFT is a registered trademark of MarshallSoft Computing. SEE4C Users Manual Page 1 C O N T E N T S Chapter Page 1.0 Introduction................................................3 1.1 Email Client Compatibility..............................5 1.2 User Support............................................5 1.3 ASP Ombudsman...........................................5 1.4 Installation............................................6 1.5 Consulting Services.....................................6 2.0 Library Overview............................................7 2.1 Dynamic Link libraries..................................7 2.2 Compiler Compatibility..................................7 2.3 Compiling Programs......................................7 2.4 Using a MAKEFILE........................................7 2.5 Using an IDE............................................8 2.6 Compiling the Example Programs.........................10 3.0 Email Basics...............................................11 3.1 Your Email Account.....................................11 3.2 Email Address Format...................................11 3.3 MIME Extensions........................................11 3.4 Your SMTP/POP3 Host Name...............................12 3.5 Editing EMAIL.H........................................13 4.0 Theory of Operation........................................14 5.0 Versions of SEE............................................15 5.1 Shareware Version......................................15 5.2 Student Version........................................15 5.3 Professional Version...................................15 6.0 Using SEE with Other Languages.............................16 7.0 Problems...................................................17 8.0 Example Programs...........................................17 8.1 SMTP Example Programs..................................17 8.2 POP3 Example Programs..................................18 9.0 Legal Issues...............................................19 9.1 Registration...........................................19 9.2 Academic Discount......................................19 9.3 License................................................20 9.4 Warranty...............................................20 10.0 Summary................................................... 21 10.1 Revision History......................................21 10.2 SEE Function Summary..................................21 10.3 SEE Error Return Code List............................22 SEE4C Users Manual Page 2 1.0 Introduction SEE4C is the easiest way to write email applications in C/C++ ! The SMTP/POP3 Email Engine (SEE) is a library of functions providing direct and simple control of the SMTP (Simple Mail Transport Protocol) and POP3 (Post Office 3) protocols. A simple interface allows sending and receiving email, including multiple MIME base64 and quoted-printable encoded attachments. Knowledge of Winsock and TCP/IP is not needed. SEE4C includes multiple C/C++ example programs. With SEE4C, you can write GUI or console mode programs that easily: (1) Send email with optional MIME attachments. (2) Get the number of messages on your email server. (3) Get the header lines from any email on your server, without reading the entire email. (4) Delete any email on the server without reading it first. (5) Receive any email on your server including MIME attachments. Ten example programs are included, demonstrating the above functions. Microsoft Foundation Class (MFC) and Borland C++ Builder (BCB) examples are also included. SEE4C supports and has been tested with Microsoft Visual C/C++, Borland C/C++, and Watcom C/C++ compilers. It can also be used with most other Windows compilers. Both Win16 and Win32 DLLs (Dynamic Link Libraries) are provided. SEE4C can be used with Windows 3.X, 95/98, and NT. The SEE4C DLLs (SEE16.DLL and SEE32.DLL) can also be used from any language (Visual Basic, ACCESS, EXCEL, Power Basic Console Compiler, Delphi, Fujitsu COBOL, ABSOFT Fortran, etc.) capable of calling the Windows API. SEE4C Users Manual Page 3 1.0 Introduction (continued) The following example demonstrates the use of the library functions: +-------------------------------------------------------------------+ | #include <windows.h> | | #include <stdio.h> | | #include "see.h" | | | | void main(int argc, char *argv[]) | | {int Code; | | /* connect to SMTP server */ | | seeSmtpConnect( | | (LPSTR)"mail.yourserver.net", /* your SMTP server */ | | (LPSTR)"user@domain.com", /* your email address */ | | (LPSTR)NULL); /* Reply-To header */ | | /* send email */ | | seeSendEmail( | | (LPSTR)"see@marshallsoft.com", /* To list */ | | (LPSTR)NULL, /* CC list */ | | (LPSTR)NULL, /* BCC list */ | | (LPSTR)"SEE Test", /* Subject */ | | (LPSTR)"This is a test.", /* Message text */ | | (LPSTR)"SEE4C20.ZIP"); /* MIME attachment */ | | /* close connection to server */ | | seeClose(); | | } | +-------------------------------------------------------------------+ In the example program above, seeSmtpConnect is called to connect to your SMTP mail host. The SMTP server host name and your email address are required, while the "Reply-To" entry is optional. seeSendEmail is then called, passing the addressee lists. The primary addressee is provided in the "To List". The CC ("Carbon Copy") lists additional recipients, as does the BCC (Blind Carbon Copy) list. The subject contains the email subject line. The message text is next. If it starts with the '@' symbol, it is considered the name of the file containing the email message. Lastly, the filename of any ASCII or binary attachment is specified. All fields in seeSendEmail are optional except the first. After returning from seeSendEmail, the seeClose function is called to close the connection to the SMTP server. Refer to the SEE4C Reference Manual for individual function details. SEE4C Users Manual Page 4 1.1 Email Client Compatibility The SMTP/POP3 Email Engine library has been tested against multiple email clients, including Eudora (Lite & Pro), Microsoft Outlook, Pegasus, Calypso, PM Mail 98, Actif Mail, Lotus Notes, and Netscape. 1.2 User Support We want you to be successful in developing your applications using SEE4C! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know. If you are having a problem using SEE4C, email us at support@marshallsoft.com You can also reach us at 256-881-4630 between 8:30 AM and 8:30 PM CST Monday through Friday. You can also often get us on the weekend. The latest versions of our products are available on our web site at http://www.marshallsoft.com and on our anonymous FTP site at ftp://ftp.marshallsoft.com/marshallsoft The MarshallSoft Computing newsletter "Comm Talk" is published quarterly on our web site. It discusses various communications problems and solutions using our products as well as related information. 1.3 ASP Ombudsman MarshallSoft Computing, Inc. is a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 157-F Love Ave., Greenwood, IN 26142 USA, FAX 317-888-2195, or send email to omb@asp-shareware.org. SEE4C Users Manual Page 5 1.4 Installation (1) Before installation of SEE4C, your Windows C/C++ compiler should already be installed on your system and tested. In particular, include command line tools when installing your compiler. (2) Make a backup copy of your distribution disk. Put your original distribution disk in a safe place. (3) Exit Windows into DOS, or start a DOS window: (4) Create your SEE project directory, copy the SEE archive, then unzip the archive. For example: MKDIR SEE4C PKUNZIP SEE4C20.ZIP SEE4C (5) Run the INSTALL batch file, which will copy the correct DLL and LIB files for your compiler. For Win32 compilers, you may choose native mode DLLs for your compiler (Microsoft, Borland, or Watcom) or "universal" mode, which requires that your compiler support the "declspec" keyword. Microsoft, Borland 5.0 and Watcom 11.0 all support "declspec". The same DLL is used for all Win16 compilers. INSTALL MS (Microsoft) INSTALL BC (Borland) INSTALL WC (Watcom) INSTALL U (Universal) (6) Before compiling any example programs, you must edit the file EMAIL.H with your email configuration as described in section 3.5. 1.5 Consulting Services We offer consulting services at $75 per hour, billed to your credit card in 10 minute increments. A work authorization letter must be signed and mailed or FAXed to us before we can start. Questions dealing with the use of our library or our example programs are covered as "support", for which there is no charge. Any other questions are considered consulting. SEE4C Users Manual Page 6 2.0 Library Overview 2.1 Dynamic Link Libraries SEE4C includes both Win16 [SEE16] and Win32 [SEE32] dynamic link libraries (DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to the traditional static library which is bound to each and every application that uses it at link time. Since SEE4C is a DLL, only one copy of the SEE4C code is loaded into memory regardless of the number of applications programs that use it. For example, more than one instance of the test program MAILER can be started. All copies of MAILER can run concurrently. 2.2 Compiler Compatibility SEE4C has been tested with Microsoft Visual C/C++, Borland C/C++ (including C++ Builder), Turbo C/C++, and Watcom C/C++. Other Windows C/C++ compiler may work as well. 2.3 Compiling Programs The example programs can be compiled by using either the provided makefiles or creating a project file for the IDE. Separate makefiles are provided for Win16 and Win32. 16-bit makefile end with "16" while 32-bit makefiles end with "32". The various Win32 compiler manufacturers each use different compiler settings so that a DLL compiled with one compiler cannot always be called by an application compiled with a different compiler. One solution is the use of the "declspec" keyword provided that your compiler supports it. This corresponds to choosing the "universal" set of DLLs when installing. See INSTALL.BAT. 2.4 Using a MAKEFILE Makefiles originated on UNIX systems. They are the standard way that C/C++ programs are constructed in command line environments. Windows programs can be constructed with makefiles running DOS using command line Windows compilers. Makefiles are provided for Microsoft, Borland, and WATCOM command line compilers. Makefiles have file extensions of "_M_" for Microsoft, "_B_" for Borland, and "_W_" for WATCOM. Thus, MAILER16._W_ is the Watcom Win16 makefile for MAILER and MAILER32._M_ is the Microsoft Win32 makefile. Turbo C/C++ for Windows and Borland C Builder do not support command line makefiles. See MAKEFILE.TXT for more information on makefiles. SEE4C Users Manual Page 7 2.5 Using an IDE All current windows compilers have an Integrated Development Environment (IDE) for building application programs in the Windows environment. Since there is no standard format for IDE project files, file names must be entered into the IDE from the keyboard. Each example program has a project text file (e.g. MAILER.PRJ) which contains the list of filenames that must be entered into the IDE. We do not distribute IDE files in our package because (1) they are very large, (2) they are not always upwardly compatible with previous versions of a particular IDE, (3) there is no standard project file format between compiler manufactures, and (4) they often must be modified to provide the correct path names. However, creating a project file within the IDE is very easy. Each application has a project file . Each project file contains the filenames that must be entered into the IDE. For each IDE, you will have to enter these filenames into the IDE. This is usually done with the INS key except for the Microsoft Developer, which uses menu commands. Be careful to enter all filenames as listed in the ".PRJ" file. All of the example application programs have been built using IDEs from Microsoft, Borland, and Watcom. However, there are differences between IDE versions from the same compiler manufacturer. All of the IDEs use the concept of a file hierarchy. For example, the MAILER file hierarchy in the IDE (for 32-bit) should look like: MAILER.EXE +++ MAILER.C +++ SEE32.LIB Replace SEE32.LIB above with SEE16.LIB for 16-bit applications. The order of the files is not significant. 2.5.1 Microsoft IDE Choose "Project", then "New". Select Win16 [Win32] as the target. A dialog box will then pop up into which the project file names are entered. SEE4C Users Manual Page 8 2.5.2 Microsoft Developer Choose "File", then "New", then "Project Workspace". Select "Application" for "Type:" and your project name for "Name:". Choose Win16 or Win32 for platform. Then select "Create". Select "Insert", then "Files into Project". Add all filenames as listed in the ".PRJ" file corresponding to the project you are building. Lastly, select "Rebuild All". 2.5.3 Borland IDE Turn off LINKER case sensitivities: Choose "Options", "Projects", "Linker", "General". Turn off the "case sensitive link" and "case sensitive exports and imports" boxes. Next, choose "Project", then "New Project". Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "GUI" for the "Target Model:" Only "Runtime" and "Dynamic" should be checked for "Standard Libraries:" NOTE1: If, after linking in the IDE, you get unresolved external references to the communications library functions in which each function name is all upper case, then you have NOT turned off case sensitivity as described above. NOTE2: If you get errors compiling the windows header file "WINDOWS.H", turn on "Borland Extensions" in "Options", "Project", "Compiler", "Source". 2.5.4 Turbo C IDE Follow the same directions as above, except that the "Target Model:" can be any listed. 2.5.5 Borland C++ Builder Choose "File" / "Open Project" on the menu bar. Load BCB_PRJ.MAK. Then, choose "Build All" from "Project" to create the executable. 2.5.6 Watcom IDE Choose "File", then "New Project". Enter the project name and then choose Win16 [Win32] as the target. Use the INS (Insert) key to pop up a dialog box into which the project file names are entered. Select "Options" from the main window, then "C Compiler Switches", then "10". Memory Models and Processor Switches". Check "80386 Stack based calling [-3s]", then check "32-bit Flat model [-mf]". SEE4C Users Manual Page 9 2.6 Compiling Example Programs There are makefiles provided for each of the example programs. For example, to compile QUICK: For Microsoft C, type: NMAKE -f QUICK16._M_ NMAKE -f QUICK32._M_ For Borland C, type: MAKE -f QUICK16._B_ MAKE -f QUICK32._B_ For Watcom C, type: WMAKE -f QUICK16._W_ WMAKE -f QUICK32._W_ Several example programs are coded for Win32 Console Mode, and therefore can NOT be compiled under Win16. The QM_PRJ example program requires Borland C++ Builder. The MFC_PGM example program requires Microsoft Foundations Classes (MFC). SEE4C Users Manual Page 10 3.0 Email Basics 3.1 Your Email Account Your email account is hosted on a computer which has a permanent connection to the Internet. Email is sent to you over the Internet using the SMTP (Simple Mail Transport Protocol) and is stored on disk until you retrieve it using the POP3 (Post Office Protocol 3) or IMAP (Internet Message Access Protocol) protocol. POP3 is a subset of IMAP, so the POP3 protocol can be used to email from a IMAP email server. The SMTP/POP3 Email Engine (SEE) is used to send and receive email using the SMTP and POP3 protocols. 3.2 Email Address Format Email addresses are always specified as "xxx<yyy@zzz>" where (1) xxx is the optional "real name". (2) yyy@zzz is the official email address, where yyy is your account name, and zzz is where your email account is hosted. (3) The brackets are required. For example, my email address can be specified by any of the following: (1) <mike@marshallsoft.com> (2) Mike<mike@marshallsoft.com> (3) Mike Marshall <mike@marshallsoft.com> Multiple email addresses can be stringed together separated by commas, as in: "<mike@myisp.com>,<pam@myisp.com>,<lauren@myisp.com>" See the sample programs for many examples of use. 3.3 MIME Extensions Internet mail can only transport 7-bit ASCII characters. Multipurpose Internet Mail Extensions (MIME) are used to allow the attachment of binary data to an email message. The standard MIME attachment types are "quoted-printable" and "base64". The SMTP/POP3 Email Engine library supports both. SEE4C Users Manual Page 11 3.3.1 Quoted-Printable Encoding Quoted-Printable encoding is primarily used to embed binary values into a email message, typically for use with foreign alphabets. To enable Quoted-Printable encoding, call seeIntegerParam(SEE_QUOTED_PRINTABLE, 1); before calling seeSendEmail. To disable Quoted-Printable encoding, call seeIntegerParam(SEE_QUOTED_PRINTABLE, 0); The default is Quoted-Printable encoding off. 3.3.2 Binary Attachments Binary attachments are encoded using MIME base-64. Most all email clients (such as made by Eudora, Netscape, and Microsoft) can decode MIME base-64 attachments. To attach a file to your email, you specify the filename as the last argument of the seeSendEmail function. Refer to the reference manual for more details. Multiple attachments are listed with commas separating them, such as "file1.zip,file2.zip,file3.zip". 3.4 Your SMTP/POP3 Host Name In order to send or receive email, you must know the name (or IP address) of your mail server. All email client programs (Eudora, etc.) must have this name in order to send email. Typically, your email server name will be "mail.XXX.YYY" where XXX.YYY is the name of the computer which hosts your email account. If you aren't sure of your email host name, look in the setup of your email client program or ask your system administrator. Before compiling any example programs, you must edit the file EMAIL.H with your email configuration as described in section 3.5. SEE4C Users Manual Page 12 3.5 Editing EMAIL.H The file EMAIL.H contains the following five defines #define SMTP_HOST_NAME "smtp_server_name" #define POP3_HOST_NAME "pop3_server_name" #define YOUR_EMAIL_ADDR "your_email_address" #define POP3_USER_NAME "pop3_account_name" #define POP3_PASSWORD "pop3_account_password" and must be edited with your email configuration before compiling any of the example programs. This information is required for all email clients. If you are unsure of any of these settings, look in your email client program (Eudora, Pegasus, etc.). SMTP_HOST_NAME is the name (or IP address) of your SMTP email server. For example, #define SMTP_HOST_NAME "mail.hiwaay.net" #define SMTP_HOST_NAME "10.240.72.1" POP3_HOST_NAME is the name of your POP3 server, which is typically the same as the SMTP server. For example, #define POP3_HOST_NAME "mail.hiwaay.net" #define POP3_HOST_NAME "10.240.72.1" Note that your email account is hosted by the POP3 server, although you could use another server (SMTP) for sending email. YOUR_EMAIL_ADDR is your email address. Brackets "<>" are required. For example, #define YOUR_EMAIL_ADDR "Mike Marshall<mike@marshallsoft.com>" POP3_USER_NAME is the account name for your email (POP3) account. For example, #define POP3_USER_NAME "marshallsoft" POP3_PASSWORD is the password for your email (POP3) account. For example, #define POP3_PASSWORD "qwerty" SEE4C Users Manual Page 13 4.0 Theory Of Operation The SMTP/POP3 Email Engine is state driven. This means that each call to SEE functions (that access the server) is broken down into sequential steps, each of which can be performed within a second or two. There are two ways in which SEE is used: (1) indirect use of the state engine, and (2) direct use of the state engine. 4.1 Indirect Method The first (or "indirect") way to use the SEE library is to allow all SEE function calls to automatically call the SEE driver (seeDriver) before returning. This is the default way that SEE operates. The major advantage of this approach is that each SEE function returns only after it has completely finished. The disadvantage of this approach is that some functions may run for a considerable amount of time during which time the calling application must wait. Refer to the sample programs MAILER and STATUS for an example of this approach. 4.2 Direct Method The second (or "direct") way that the SEE state driver is used is to call it (seeDriver) directly. In order to operate this way, the function seeIntegerParam must be called which sets the AUTO_CALL flag to off: seeIntegerParam(SEE_AUTO_CALL_DRIVER, 0); After the above statement is executed, the state driver (seeDriver) must be called after all other SEE functions that access the server. For example, Code = seeSmtpConnect(...); if(Code<0) {/* handle error here */} while(1) {/* call the driver */ Code = seeDriver(); if(Code<0) {/* handle error here */} if(Code==0) break; /* do something here . . . */ } The major advantage of the direct approach is that the calling application can perform other work such as reporting the progress of large downloads. The disadvantage is the extra code that must be written to call seeDriver. Refer to the sample programs FROM and READER for an example of this approach. SEE4C Users Manual Page 14 5.0 Versions of SEE The SMTP/POP3 Email Engine (SEE) library is available in three versions. All three versions have identical functionality. 5.1 Shareware Version The shareware version can be differentiated from the other two versions by: (1) The shareware reminder screen is displayed at startup. (2) The "X-Registered-To: " header in all outgoing email is branded with "X-Registered-To: SHAREWARE VERSION [http://www.marshallsoft.com]" (3) All email is followed by the following two lines: "___________________________________________________________________" "MarshallSoft SMTP/POP3 Engine. Programmers see www.marshallsoft.com" The Shareware version may not be used for commercial purposes. 5.2 Student Version The student version can be differentiated from the other two versions by: (1) There is no shareware reminder screen. (2) The "X-Registered-To: " header in all outgoing email is branded with "X-Registered-To: STUDENT VERSION [http://www.marshallsoft.com]" (3) There are no lines added to the end of the email as in the shareware version. The Student version may not be used for commercial purposes. 5.3 Professional Version The professional version can be differentiated from the other two versions by: (1) There is no shareware reminder screen. (2) The "X-Registered-To: " header in all outgoing email is branded with your company name. (3) There are no lines added to the end of the email as in the shareware version. The professional version may be distributed with your application as as specified by the software license. SEE4C Users Manual Page 15 6.0 Using SEE with Other Languages The SMTP/POP3 Email Engine DLLs can be used with any application written in ANY language capable of calling the Windows (3.1, 95/98, NT) API. SEE16.DLL is required for all Win16 (Windows 3.1) applications, and SEE32.DLL is required for all Win32 (Windows 95/98/NT) applications. Declaration files have been defined by the following languages: C/C++ : SEE.H Visual Basic : SEE16.BAS & SEE32.BAS EXCEL & ACCESS : SEE16.BAS & SEE32.BAS Power Basic CC : SEE32.BAS [not the same as above] Borland Delphi : SEE16.PAS & SEE32.PAS Fujitsu COBOL : SEE32.CBI Visual FoxPro : SEE32.FOX Additional declaration files will be added. Give us a call if you need a declaration not listed above. If you have interfaced SEE to an unusual language, email us the declaration file! 6.0 Problems Before attempting to run any of the example programs, you should already be able to connect to the Internet and run your email client program, such as Eudora or Pegasus Mail. If you cannot get your application to run properly, first compile and run the example programs. If you call us to report a possible bug in the library, the first thing we will ask is if the example programs run correctly. Be sure to test the code returned from SEE functions. Then, call seeErrorText to get the text associated with the error code. For example: Code = seeSmtpConnect("mail.isp.net","<mike@marshallsoft.com>",NULL); if(Code<0) {static char Buffer[64]; seeErrorText(Code,Buffer,64); printf("Error %d: %s\n", Code, Buffer); } If you encounter a problem that you cannot resolve, give us a call or email us at support@marshallsoft.com. SEE4C Users Manual Page 16 8.0 Example Programs Before compiling any of the example programs, edit the file EMAIL.H with your email configuration as explained in section 3.5 "Editing EMAIL.H". 8.1 SMTP Example Programs There are 6 SMTP example programs. SMTP programs send email. 8.1.1 MULTI MULTI is a Win32 console mode program that connects to a SMTP server and sends two email messages. This is the first SMTP example program to edit, compile, and run. 8.1.2 MAILER MAILER is a Win32 console mode program that emails a message, taking its input from the command line. 8.1.3 QUICK QUICK is a Win16/Win32 GUI (Graphical User Interface) application that emails a message entered into a dialog box. 8.1.4 QM "Quick Message" (QM_PRJ & QM_PGM) is a Borland C++ Builder (Win32 GUI) program that emails a message from the GUI. Borland C++ Builder is required to compile this program. 8.1.5 MFC_PGM MFC_PGM is a Microsoft Foundation Class (MFC) example program. Win16 (MFCPGM16.MAK) and Win32 (MFCPGM32.MAK) makefiles are provided. File NAFXCW.LIB may have to be copied from MFC\LIB on your Microsoft Visual C/C++ CD disk. 8.1.6 BCAST BCAST is a Win32 console mode program which emails the same message (BCAST.MAI) to a list of addresses taken from the file BCAST.EML. Please DO NOT use this for spam! SEE4C Users Manual Page 17 8.2 POP3 Example Programs There are 5 POP3 example programs. These examples read email. 8.2.1 STAT STAT is a very simple Win32 console modem program that returns the number of email messages waiting on the POP3 server. This is the first POP3 example to edit, compile, and run. 8.2.2 FROM FROM is a Win16/Win32 GUI application that reads and displays selected header information, without reading the entire email message. FROM also makes a very handy utility program. 8.2.3 STATUS STATUS is the Win32 console mode equivalent of FROM. 8.2.4 DELETE DELETE is a Win32 console mode program that deletes an email message from the server. Be careful! Once deleted, an email message cannot be recovered. 8.2.5 READER READER is a Win32 console mode program that reads an email message, including MIME attachments, saving it to disk. For example, to read email message #1 and save it as file MYMAIL.TXT, READER 1 MYMAIL.TXT SEE4C Users Manual Page 18 9.0 Legal Issues 9.1 Registration The professional version of SEE4C may be registered for $95 plus $7 S&H ($12 outside of North America) . The professional registered DLLs may be distributed (without royalty) in object form only, as part of the user's application, provided that the application is NOT a compiler, interpreter, or other software development program. The professional version DLL is also branded with your company name. To order, contact us as shown on the title page of this manual. All prices are guaranteed for one year from the release date. Multiple copy discounts (3 or more) and site licenses are available. Please call for details. We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, purchase orders (POs) from recognized US schools and companies listed in Dun & Bradstreet, and COD (street address and phone number required) within the USA (plus a $5 COD charge). For credit card orders, be sure to include the account number, the expiration date, the exact name on the card, and the complete card billing address (the address to which the credit card bill is mailed). Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes: o Win16 & Win32 SEE4C Libraries w/o shareware screens. o Printed Users Manual & Reference Manual. o Telephone and email support for one year. The registered user will receive the latest version of SEE4C shipped by US second day priority mail (packet airmail overseas). A 3.5" HD diskette is provided. 9.2 Academic Discount We offer an "academic price" of 40% off the normal price for prepaid email orders to faculty and students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school. When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page . Your order will be sent to your email address at your school. This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing can not be used for any commercial purpose. SEE4C Users Manual Page 19 9.3 License MarshallSoft Computing, Inc. grants the registered user of SEE4C the right to use one copy of the SEE4C library (in object form) on a single computer in the development of any software product (other than libraries such as SEE4C). The user may not use the the library on more than one computer at the same time. The "student" (40% academic discount) registered DLLs may not be distributed under any circumstances, nor may they be used for any commercial purpose. The "professional" ($95) registered DLLs may be distributed (without royalty) in object form only, as part of the user's application, provided that the DLLs are NOT distributed publicly. 9.4 Warranty MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE. Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you. This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts. SEE4C Users Manual Page 20 10.0 Summary 10.1 Revision History Version 1.0 "Beta": May 23, 1998. o The Beta release. Version 1.0: June 1, 1998. o The official release of version 1.0. Version 2.0: September 14, 1998. o A major update adding POP3 capability. o Another SMTP example program (BCAST). 10.2 SEE4C Function Summary Refer to the SEE4C Reference Manual (SEE4C_R.TXT) for detailed information on the communications and support functions. A one line summary of each function follows. There are 16 functions in the SEE library. +-------------------+-----------------------------------------------+ | seeClose | Closes SMTP/POP3 Email Engine. | | seeDelete | Deletes email. | | seeSmtpConnect | Connects to SMTP server. | | seeDebug | Returns debug information. | | seeDriver | Executes next SEE state. | | seeExtractText | Extracts line contining specified text. | | seeErrorText | Get text associated with error code. | | seeGetEmailCount | Get number of emails waiting on server. | | seeGetEmailFile | Read email file and save to disk. | | seeGetEmailLines | Read email lines into buffer. | | seeIntegerParam | Sets SEE integer parameter. | | seePop3Connect | Connects to POP3 server. | | seeSendEmail | Sends email and attachments. | | seeStatistics | Returns runtime statistics. | | seeStringParam | Sets SEE string parameter. | | seeVerifyFormat | Check email address. | +-------------------+-----------------------------------------------+ SEE4C Users Manual Page 21 10.3 SEE Error Return Code List The complete list of SEE error codes follows. +-----------------------+-----------------------------------------+ | SEE_NO_ERROR | No error. | | SEE_CANNOT_COMPLY | Cannot comply. Not always an error. | +-----------------------+-----------------------------------------+ | SEE_EOF | End of file (socket has been closed). | | SEE_IS_BLOCKING | Socket is currently blocking. | | SEE_BAD_DOTTED | Bad dotted address. | | SEE_TIMED_OUT | Socket timed out awaiting data. | | SEE_ABORTED | The DLL has been corrupted. | | SEE_ALREADY_CONNECTED | Already connected to server. | | SEE_BACK_OVERFLOW | Response buffer has overflowed. | | SEE_BAD_ADDRESS_CHAR | Bad character in email address. | | SEE_CANNOT_ATTACH | Cannot access WINSOCK | | SEE_CANNOT_OPEN | Cannot open file. | | SEE_CONNECT_ERROR | Error attempting to connect. | | SEE_EMPTY_ADDRESS | EMPTY email address. | | SEE_FROM_NULL_ARG | FromPtr is NULL. | | SEE_MISSING_AT_CHAR | Missing '@' character in email address. | | SEE_MISSING_FROM | Missing FROM email address. | | SEE_MISSING_LEFT | Missing '<' delimiter in email address. | | SEE_MISSING_RIGHT | Missing '>' terminating email address. | | SEE_NOT_CONNECTED | Not connected to server | | SEE_NO_RECEIPIENTS | Must have at least one receipient. | | SEE_NO_SERVER | Cannot find Smtp server. | | SEE_NULL_POINTER | Unexpected NULL pointer. | | SEE_RCPT_NULL_ARG | ToPtr is NULL. | | SEE_SMTP_ERROR | SMTP returned error. | | SEE_SMTP_NULL_ARG | SMTP Server not specified. | | SEE_SOCK_READ_ERROR | Socket read error. | | SEE_SOCK_WRITE_ERROR | Socket write error. | | SEE_TOO_MANY_AT_CHARS | Too many '@' symbols in email address. | | SEE_SMTP_ONLY | Must be connected to SMTP server. | | SEE_POP3_ONLY | Must be connected to POP3 server. | | SEE_USER_NULL_ARG | Required POP3 user argument is missing. | | SEE_PASS_NULL_ARG | Required POP3 password argument missing.| | SEE_POP3_ERROR | Error returned by POP3 server. | | SEE_MSG_NBR_RANGE | Message number out of range. | | SEE_FILENAME_NULL_ARG | Required filename is missing. | | SEE_EMAIL_PATH_NULL | Required file path is missing. | | SEE_CANNOT_CREATE | Cannot create file. | | SEE_BUFFER_NULL_ARG | Required buffer is missing. | +-----------------------+-----------------------------------------+ NOTES: (1) All error codes are negative. (2) Numerical error codes are defined in DEFINES.H. (3) SEE_ABORTED will be returned if the DLL has been modified. You should never get this message! SEE4C Users Manual Page 22